package cn.lg.soar.core.manager;

import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.Lock;

/**
 * @author luguoxiang
 * 开源项目：https://gitee.com/lgx1992/lg-soar 求star！请给我star！请帮我点个star！
 */
public interface SoarLock extends Lock {
    /**
     * 获取该锁对象的名称（通常对应 Redis 中的 key 名称）
     *
     * @return 锁的名称（key）
     */
    String getName();

    /**
     * 可中断地获取锁，并指定锁的最大持有时间。
     * 如果当前锁被其他线程占用，则当前线程会阻塞等待，直到锁可用。
     *
     * 如果设置了 leaseTime，锁会在指定时间后自动释放；
     * 如果设置为 -1，则锁不会自动释放，必须手动调用 unlock()。
     *
     * @param leaseTime 锁的最大持有时间，-1 表示不自动释放
     * @param unit 时间单位
     * @throws InterruptedException 如果线程被中断
     */
    void lockInterruptibly(long leaseTime, TimeUnit unit) throws InterruptedException;

    /**
     * 尝试获取锁，最多等待 waitTime 时间，并指定锁的持有时间 leaseTime。
     * 如果在 waitTime 内无法获取到锁，则返回 false。
     *
     * 锁会在 leaseTime 时间后自动释放。
     *
     * @param waitTime 最多等待获取锁的时间
     * @param leaseTime 锁的持有时间，-1 表示不自动释放
     * @param unit 时间单位
     * @return true 如果成功获取锁；false 如果超时或锁已被占用
     * @throws InterruptedException 如果线程被中断
     */
    boolean tryLock(long waitTime, long leaseTime, TimeUnit unit) throws InterruptedException;

    /**
     * 获取锁，并指定锁的最大持有时间。
     * 如果当前锁被其他线程占用，则当前线程会阻塞等待，直到锁可用。
     *
     * 锁会在指定时间后自动释放。
     *
     * @param leaseTime 锁的最大持有时间，-1 表示不自动释放
     * @param unit 时间单位
     */
    void lock(long leaseTime, TimeUnit unit);

    /**
     * 强制解锁，不管当前锁是否由当前线程持有。
     * 适用于异常情况下恢复锁状态。
     *
     * @return true 如果锁存在并成功删除；false 如果锁不存在
     */
    boolean forceUnlock();

    /**
     * 检查锁是否已经被任何线程持有。
     *
     * @return true 如果锁被持有；false 如果未被持有
     */
    boolean isLocked();

    /**
     * 检查指定线程 ID 的线程是否持有了当前锁。
     *
     * @param threadId 要检查的线程 ID
     * @return true 如果该线程持有了锁
     */
    boolean isHeldByThread(long threadId);

    /**
     * 检查当前线程是否持有了当前锁。
     *
     * @return true 如果当前线程持有了锁
     */
    boolean isHeldByCurrentThread();

    /**
     * 获取当前线程对该锁的重入次数（即加锁了多少次）。
     *
     * @return 当前线程的重入次数，如果没有持有锁则返回 0
     */
    int getHoldCount();

    /**
     * 获取锁的剩余存活时间（TTL），以毫秒为单位。
     *
     * @return 剩余存活时间（毫秒）
     *         -2 表示锁不存在
     *         -1 表示锁存在但没有设置过期时间
     */
    long remainTimeToLive();

}
